package com.base.web.common;

import java.io.Serializable;
import java.util.List;

import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;
import org.springframework.data.domain.Sort;
import org.springframework.data.jpa.domain.Specification;

/**
 * 基本的服务接口,可以对一些基本的能力进行抽象，基本处理一般请求.
 * 
 * @param <T>
 * @param <ID>
 * 
 * @version 2016年1月9日
 */
public interface BaseService<T, ID extends Serializable> {

    /**
     * 求总数 Returns the number of entities available .
     * 
     * @return the number of entities
     */
    long count();

    /**
     * 根据主键判断是否存在数据库中 Returns whether an entity with the given id exists .
     * 
     * @param id
     *            must not be {@literal null}.
     * @return true if an entity with the given id exists, {@literal false} otherwise
     * @throws IllegalArgumentException
     *             if {@code id} is {@literal null}
     */
    boolean exists(ID id);

    /**
     * 保存对象 Saves a given entity. Use the returned instance for further operations as the save
     * operation might have changed the entity instance completely.
     * 
     * @param entity
     * @return the saved entity
     */
    <S extends T> S save(S entity);

    /**
     * 保存对象 Saves all given entities.
     * 
     * @param entities
     * @return the saved entities
     * @throws IllegalArgumentException
     *             in case the given entity is {@literal null}.
     */
    <S extends T> List<S> save(Iterable<S> entities);

    /**
     * 保存对象 Saves an entity and flushes changes instantly.
     * 
     * @param entity
     * @return the saved entity
     */
    <S extends T> S saveAndFlush(S entity);

    /**
     * 查找 Returns a reference to the entity with the given identifier.
     * 
     * @param id
     *            must not be {@literal null}.
     * @return a reference to the entity with the given identifier.
     * @see EntityManager#getReference(Class, Object)
     */
    T getOne(ID id);

    /**
     * 查找 Retrieves an entity by its id.
     * 
     * @param id
     *            must not be {@literal null}.
     * @return the entity with the given id or {@literal null} if none found
     * @throws IllegalArgumentException
     *             if {@code id} is {@literal null}
     */
    T findOne(ID id);

    /**
     * 查找 Returns a {@link Page} of entities meeting the paging restriction provided in the
     * {@code Pageable} object.
     * 
     * @param pageable
     * @return a page of entities
     */
    Page<T> findAll(Pageable pageable);

    /**
     * 查找 分页查找所有符合条件.
     * 
     * @param pageable
     */
    Page<T> findAll(Specification<T> spec, Pageable page);

    /**
     * 查找 Returns all instances of the type.
     * 
     * @return all entities
     */
    List<T> findAll();

    /**
     * (non-Javadoc) 查找@see
     * org.springframework.data.repository.PagingAndSortingRepository#findAll(org.springframework.
     * data.domain.Sort)
     */
    List<T> findAll(Sort sort);

    /**
     * 查找 Returns all instances of the type with the given IDs.
     * 
     * @param ids
     * @return
     */
    List<T> findAll(Iterable<ID> ids);

    /**
     * Flushes all pending changes to the database.
     */
    void flush();

    /**
     * 删除 Deletes the given entities in a batch which means it will create a single {@link Query}.
     * Assume that we will clear the {@link javax.persistence.EntityManager} after the call.
     * 
     * @param entities
     */
    void deleteInBatch(Iterable<T> entities);

    /**
     * 删除 Deletes all entites in a batch call.
     */
    void deleteAllInBatch();

    /**
     * 删除 Deletes the entity with the given id.
     * 
     * @param id
     *            must not be {@literal null}.
     * @throws IllegalArgumentException
     *             in case the given {@code id} is {@literal null}
     */
    void delete(ID id);

    /**
     * 删除 Deletes a given entity.
     * 
     * @param entity
     * @throws IllegalArgumentException
     *             in case the given entity is {@literal null}.
     */
    void delete(T entity);

    /**
     * 删除 Deletes the given entities.
     * 
     * @param entities
     * @throws IllegalArgumentException
     *             in case the given {@link Iterable} is {@literal null}.
     */
    void delete(Iterable<? extends T> entities);

    /**
     * 删除 Deletes all entities managed by the repository.
     */
    void deleteAll();

}
